home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / FileManager.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  38KB  |  977 lines
  1. /*
  2.      File:        FileManager.h
  3.  
  4.      Contains:    FileManager Interface
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __FILEMANAGER__
  19. #define __FILEMANAGER__
  20.  
  21. #ifndef __FILEMANAGERTYPES__
  22. #include <FileManagerTypes.h>
  23. #endif
  24. #ifndef __FILES__
  25. #include <Files.h>
  26. #endif
  27. #ifndef __FINDER__
  28. #include <Finder.h>
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT_SUPPORTED
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=power
  41. /* the following contents can only be used by compilers that support PowerPC struct alignment */
  42.  
  43. /* You can use FileManager.h or FileManagerSPI.h, but not both */
  44. #ifndef _FILEMANAGERSPI__
  45. #if FOR_SYSTEM8_PREEMPTIVE
  46. /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>> F o u n d a t i o n  D e f i n i t i o n s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/
  47. /*
  48. ****************************************************************************
  49.     CONSTANTS & TYPES
  50. ****************************************************************************
  51. */
  52.  
  53. enum {
  54.     kFSInfoInvalidVersion        = 0,
  55.     kFSInfoD10Version            = 1,
  56.     kFSInfoD11Version            = 2,
  57.     kFSInfoCurrentReleasedVersion = kFSInfoD11Version
  58. };
  59.  
  60. typedef UInt32 FSInfoVersion;
  61.  
  62. enum {
  63.     kFSHFSPath                    = 1,
  64.     kFSUnixPath                    = 2,
  65.     kFSDOSPath                    = 3
  66. };
  67.  
  68. typedef UInt32 FSPathnameType;
  69.  
  70. enum {
  71.     kFSFileIsLocked                = 0x00000001
  72. };
  73.  
  74. typedef OptionBits FSFileFlags;
  75. struct FSFileInformation {
  76.     FSFileFlags                     flags;
  77.  
  78.     FInfo                             finderInfo;
  79.     FXInfo                             extendedFinderInfo;
  80.  
  81.     FSDate                             creationDate;
  82.     FSDate                             modificationDate;
  83.  
  84.     FSSize                             dataForkSize;
  85.     FSSize                             resourceForkSize;
  86. };
  87. typedef struct FSFileInformation FSFileInformation;
  88.  
  89. typedef FSFileInformation *FSFileInformationPtr;
  90.  
  91. enum {
  92.     kFSFolderIsLocked            = 0x00000001
  93. };
  94.  
  95. typedef OptionBits FSFolderFlags;
  96. struct FSFolderInformation {
  97.     FSFolderFlags                     flags;
  98.  
  99.     DInfo                             finderInfo;
  100.     DXInfo                             extendedFinderInfo;
  101.  
  102.     FSDate                             creationDate;
  103.     FSDate                             modificationDate;
  104. };
  105. typedef struct FSFolderInformation FSFolderInformation;
  106.  
  107. typedef FSFolderInformation *FSFolderInformationPtr;
  108.  
  109. enum {
  110.     kFSVolumeIsLockedInHardware    = 0x00000001,
  111.     kFSVolumeIsLockedInSoftware    = 0x00000002,
  112.     kFSVolumeIsLockedMask        = kFSVolumeIsLockedInHardware | kFSVolumeIsLockedInSoftware,
  113.     kFSVolumeIsEjectable        = 0x00000004,
  114.     kFSVolumeIsOffline            = 0x00000008,
  115.     kFSVolumeIsRemote            = 0x00000010
  116. };
  117.  
  118. typedef OptionBits FSVolumeFlags;
  119. struct FSVolumeInformation {
  120.     FSFolderInformation             folderInfo;
  121.  
  122.     FSVolumeFlags                     flags;
  123.  
  124.     FSSize                             totalBytes;
  125.     FSSize                             freeBytes;
  126.     FSMountAccessConstraints         constraints;
  127.     FSVolumeCapabilities             capabilities;
  128. };
  129. typedef struct FSVolumeInformation FSVolumeInformation;
  130.  
  131. typedef FSVolumeInformation *FSVolumeInformationPtr;
  132. struct FSObjectInformation {
  133.     FSObjectType                     objectType;
  134.  
  135.     union {
  136.         FSFileInformation                 fileInfo;
  137.         FSFolderInformation             folderInfo;
  138.         FSVolumeInformation             volumeInfo;
  139.     }                                 info;
  140. };
  141. typedef struct FSObjectInformation FSObjectInformation;
  142.  
  143. typedef FSObjectInformation *FSObjectInformationPtr;
  144. /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C O N T A I N E R S <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/
  145. /*
  146. ****************************************************************************
  147.     OBJECTS
  148. ****************************************************************************
  149. */
  150. /*
  151.     Function:    FSObjectRefClone
  152.     Purpose:    Return a copy of an FSObjectRef such that the copy also needs to be disposed.
  153.     Inputs:
  154.                 object_t        The object ref to be cloned.
  155.     Outputs:
  156.                 clone_o            Copy of object_t.
  157.     Notes:
  158.                 The value returned is the same value passed as input in object_t.  This call
  159.                 would typically be used to balance a future call to FSObjectRefDispose.  Some
  160.                 examples where it might be used:
  161.                     * A called procedure needs to save an FSObjectRef for future use, but the
  162.                       calling conventions dictate that the caller is responsible for disposing
  163.                       of the ref.  The called function could call FSObjectRefClone to make its
  164.                       copy.  The caller can safely dispose of the ref, yet the callee can use
  165.                       the ref until doing its own dispose.
  166.                     * In object-oriented programming, an object could be passed an FSObjectRef
  167.                       in its constructor.  The destructor would be expected to dispose the ref,
  168.                       but so would the routine that created the object.  FSObjectRefClone could
  169.                       be used in the constructor.
  170.                 
  171.                 The returned FSObjectRef is registered to the calling process (as must object_t).
  172. */
  173. extern OSStatus FSObjectRefClone(FSObjectRef object_t, FSObjectRef *clone_o);
  174.  
  175. /*
  176.     Function:    FSObjectRefDispose
  177.     Purpose:    Dispose of an FSObjectRef previously returned to a process.
  178.     Inputs:
  179.                 object_t        The object ref to be disposed.
  180.     Outputs:
  181.     Notes:
  182.                 A process must dispose of all FSObjectRefs returned to it.  The FSObjectRefs
  183.                 may be returned as explicit output parameters, or as properties.  If a ref
  184.                 is returned several times for a given object, it must be disposed for each
  185.                 time it was returned.
  186.                 
  187.                 When all refs to a given object are disposed, the File Manager will dispose
  188.                 of any resources it allocated in order to operate on that object.  All refs
  189.                 for a process will be automatically disposed upon process termination.
  190.                 
  191.                 For refs returned as properties (especially when iterating over muliple
  192.                 objects), the FSObjectRefDisposeBulk call may be more convenient.
  193. */
  194. extern OSStatus FSObjectRefDispose(FSObjectRef object_t);
  195.  
  196. /*
  197.     Function:    FSObjectFlush
  198.     Purpose:    Flushes any data cached by the File Manager for the given object.
  199.     Inputs:
  200.                 object_t        The object to be flushed.
  201.     Outputs:
  202.     Notes:
  203.                 If object_t is a file, then any data written to that file (via a stream or backing store,
  204.                 regardless of the process that opened the stream or backing store) will be written by the
  205.                 File Manager to any underlying device.  If object_t is a volume, then any data written to
  206.                 any file on that volume will be flushed.
  207.                 
  208.                 Any change to properties of object_t will be flushed (regardless of the object's type).
  209.                 
  210.                 Data about the object (or contained in the object) may still reside in the File Manager's
  211.                 caches, but any changes will have been written out by the File Manager.  Note that the
  212.                 underlying device's driver, or the device itself, may cache some data, so the File Manager
  213.                 cannot guarantee that all data has actually been written to the underlying media.
  214.  
  215.  
  216.  
  217. */
  218. extern OSStatus FSObjectFlush(FSObjectRef object_t);
  219.  
  220. /*
  221.     Function:    FSObjectRefRegister
  222.     Purpose:    Allow an FSObjectRef to be used by another process.
  223.     Inputs:
  224.                 senderObject_t        The object ref.
  225.                 receiverPid_i        The other process that will be using senderObject_t.
  226.     Outputs:
  227.     Notes:
  228.                 This call allows one process to send an FSObjectRef to another process
  229.                 such that the other process can use the FSObjectRef itself.  The process
  230.                 specified by receiverPid_i must also dispose of senderObject_t.  The File
  231.                 Manager acts as if senderObject_t has been returned to receiverPid_i.
  232.  
  233.  
  234.  
  235.  
  236.  
  237.                 You might use this call if you have several processes where one process
  238.                 (typically a server of some kind) obtains FSObjectRefs for use by other
  239.                 processes (typically clients of that server).  If the other process (as
  240.                 specified by receiverPid_i) won't actually call the File Manager with
  241.                 that FSObjectRef, then it doesn't need to be registered to that process.
  242.  
  243.                 It would also be possible to have the server process make all of the
  244.                 calls to the File Manager.  FSObjectRefs could still be passed between
  245.                 client and server, but if the clients never use the refs directly, then
  246.                 there would be no need to register the refs to those clients.  (But beware:
  247.                 the server would still be responsible for disposing of all refs returned to
  248.                 it; the server would probably have some cleanup and disposal to do if one
  249.                 of its client processes were to terminate.)
  250. */
  251. extern OSStatus FSObjectRefRegister(FSObjectRef senderObject_t, KernelProcessID receiverPid_i);
  252.  
  253. /*
  254. ============================================================================
  255.     Volume Sets
  256. ============================================================================
  257. */
  258. /*
  259.     Function:    FSVolumeSetGetInformation
  260.     Purpose:    Returns an FSObjectRef for a Volume Set specified by an
  261.                 FSVolumeSetObjID.
  262.     Inputs:
  263.                 volumeSet_t                The volume set.
  264.     Outputs:
  265.                 object_o                Object ref for the volume set.
  266.                 includesBootVolume_o    True if the volume set includes the boot volume.
  267.     Notes:
  268.                 There is currently only one volume set.  In the future there could be others
  269.                 (perhaps file servers; perhaps to support multiple local users).
  270. */
  271. extern OSStatus FSVolumeSetGetInformation(FSVolumeSetObjID volumeSet_t, Boolean *includesBootVolume_o, FSObjectRef *object_o);
  272.  
  273. /*
  274. ============================================================================
  275.     Folders
  276. ============================================================================
  277. */
  278. /*
  279.     Function:    FSFolderCreate
  280.     Purpose:    Create a new named folder within a specified folder
  281.     Inputs:
  282.                 containerRef_t        The object ref of the parent of the new folder.
  283.                 folderName_i        The name of the new folder as a _persistent_ TextObject.
  284.     Outputs:
  285.                 folderRef_o            The object ref of the new folder.
  286.     Notes:
  287.                 An error will be returned if the folder already exists.
  288. */
  289. extern OSStatus FSFolderCreate(FSObjectRef containerRef_t, ConstFSName folderName_i, FSObjectRef *folderRef_o);
  290.  
  291. /*
  292. ============================================================================
  293.     Files
  294. ============================================================================
  295. */
  296. /*
  297.     Function:    FSFileCreate
  298.     Purpose:    Create a new named file within a specified folder
  299.     Inputs:
  300.                 containerRef_t        The object ref of the parent of the new file.
  301.                 fileName_i            The name of the new file as a _persistent_ TextObject.
  302.                 fileCreator_i        The new file's Finder creator.
  303.                 fileType_i            The new file's Finder type.                
  304.     Outputs:
  305.                 fileRef_o            The object ref of the new file.
  306.     Notes:
  307.                 An error will be returned if the file already exists.
  308. */
  309. extern OSStatus FSFileCreate(FSObjectRef containerRef_t, ConstFSName fileName_i, OSType fileCreator_i, OSType fileType_i, FSObjectRef *fileRef_o);
  310.  
  311. /*
  312. ============================================================================
  313.     Folder and File Requests
  314. ============================================================================
  315. */
  316. /*
  317.     Function:    FSObjectDelete
  318.     Purpose:    Deletes an object.  The FSObjectRef is NOT disposed; you must still dispose it yourself.
  319.                 Further attempts to use the ref will return errors (such as E_ObjectNotFound).
  320.  
  321.     Inputs:
  322.                 object_t        The object to be deleted.
  323.     Outputs:
  324. */
  325. extern OSStatus FSObjectDelete(FSObjectRef object_t);
  326.  
  327. /*
  328.     Function:    FSObjectMoveRename
  329.     Purpose:    Move a file or folder to a new folder and (optionally) rename it.
  330.     Inputs:
  331.                 sourceObjectRef_t    The object ref of the file or folder to move.
  332.                 destContainerRef_i    The object ref of the new parent folder.
  333.                 newObjectName_i        The new name for the moved file or folder (optional).
  334.     Outputs:
  335.     Notes:
  336.                 An error will be returned if another file or folder exists in the
  337.                 folder specified by destContainerRef_i which has the same name as
  338.                 sourceObjectRef_t.
  339. */
  340. extern OSStatus FSObjectMoveRename(FSObjectRef sourceObjectRef_t, FSObjectRef destContainerRef_i, ConstFSName newObjectName_i);
  341.  
  342. /*
  343.     Function:    FSObjectRename
  344.     Purpose:    Rename a file or folder.
  345.     Inputs:
  346.                 sourceObjectRef_t    The object ref of the file or folder to rename.
  347.                 newObjectName_i        The new name for the file or folder.
  348.     Outputs:
  349.     Notes:
  350.                 An error will be returned if another file or folder exists in the
  351.                 same folder as sourceObjectRef_t with the name newObjectName_i.
  352. */
  353. extern OSStatus FSObjectRename(FSObjectRef sourceObjectRef_t, ConstFSName newObjectName_i);
  354.  
  355. /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C a p a b i l i t i e s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/
  356. /*
  357. ****************************************************************************
  358.     PROPERTY ACCESS METHODS
  359. ****************************************************************************
  360. */
  361. /*
  362. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  363.     Object Property Simple Values
  364. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  365. */
  366. /*
  367.     Function:    FSObjectGetOneProperty
  368.     Purpose:    Get one property attribute of an object.
  369.     Inputs:
  370.                 objectRef_t            The object ref.
  371.                 property_i            The property attribute to get.
  372.                 propertySize_i        The size of the property buffer specified
  373.                                     by propertyValue_o
  374.     Outputs:
  375.                 property_o            The requested property data.
  376.     Notes:
  377.                 This function can be used to get the value of a simple property as
  378.                 well as other attributes of all properties such as size, type,
  379.                 state, etc. The attribute to get is specified by
  380.                 property_i->attribute.
  381.                 
  382.                 Fork property values must be obtained by using the stream or mapped
  383.                 file access routines.
  384. */
  385. extern OSStatus FSObjectGetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, LogicalAddress property_o);
  386.  
  387. /*
  388.     Function:    FSObjectGetInformation
  389.     Purpose:    Get a predefined aggregate property set for an object.
  390.     Inputs:
  391.                 objectRef_t            The object ref.
  392.                 infoVersion_i        The version of the FSObjectInformation data record
  393.                                     specified by objectInfo_o.
  394.     Outputs:
  395.                 objectInfo_o        The aggregate property data (optional).
  396.                 objectName_o        The name of the specified object (optional).
  397.     Notes:
  398.                 Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  399.                 version of the FSObjectInformation record. infoVersion_i is ignored
  400.                 if objectInfo_o is omitted.
  401.                 
  402.                 objectName_o, if specified, must reference a preinitialized persistent
  403.                 TextObject of sufficient size to contain the object's name.
  404. */
  405. extern OSStatus FSObjectGetInformation(FSObjectRef objectRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *objectInfo_o, FSName objectName_o);
  406.  
  407. /*
  408.     Function:    FSObjectGetVolumeInformation
  409.     Purpose:    Get a predefined aggregate property set for a volume object.
  410.     Inputs:
  411.                 volumeItemRef_t        The object ref of a file or folder on the volume or
  412.                                     the volume itself.
  413.                 infoVersion_i        The version of the FSObjectInformation data record
  414.                                     specified by volumeInfo_o.
  415.     Outputs:
  416.                 volumeInfo_o        The aggregate volume property data (optional).
  417.                 volumeObjectRef_o    The object ref of the volume (optional).
  418.                 volumeName_o        The name of the volume (optional).
  419.     Notes:
  420.                 Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  421.                 version of the FSObjectInformation record. infoVersion_i is ignored
  422.                 if volumeInfo_o is omitted.
  423.                 
  424.                 volumeName_o, if specified, must reference a preinitialized persistent
  425.                 TextObject of sufficient size to contain the volume's name.
  426.                 
  427.                 This function is functionally equivalent to FSObjectGetInformation when
  428.                 the target object ref is the volume's object ref.
  429. */
  430. extern OSStatus FSObjectGetVolumeInformation(FSObjectRef volumeItemRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *volumeInfo_o, FSObjectRef *volumeObjectRef_o, FSName volumeName_o);
  431.  
  432. /*
  433.     Function:    FSObjectSetOneProperty
  434.     Purpose:    Set one property attribute of an object.
  435.     Inputs:
  436.                 objectRef_t            The object ref.
  437.                 property_i            The property attribute to set.
  438.                 propertySize_i        The size of the property buffer specified
  439.                                     by propertyValue_i.
  440.                 propertyData_i        The new property data.
  441.     Outputs:
  442.     Notes:
  443.                 Fork property values must be changed by using the stream or mapped
  444.                 file access routines.
  445. */
  446. extern OSStatus FSObjectSetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, ConstLogicalAddress propertyData_i);
  447.  
  448. /*
  449. ============================================================================
  450.     Stream-based Access Method
  451. ============================================================================
  452. */
  453. /*
  454.     Function:    FSStreamClose
  455.     Purpose:    Close a stream previously opened with FSStreamOpen or FSStreamOpenWithConstraints.
  456.     Inputs:
  457.                 stream_t            The stream to close.
  458.     Outputs:
  459.     Notes:
  460.                 Any data written to the stream is flushed (written by the File Manager) before the
  461.                 stream is closed.  The FSStreamObjID, stream_t, may no longer be used.  Any resources
  462.                 allocated by the File Manager for use by this stream will be disposed.
  463. */
  464. extern OSStatus FSStreamClose(FSStreamObjID stream_t);
  465.  
  466. /*
  467.     Function:    FSStreamFlush
  468.     Purpose:    Any data written to the stream will be written by the File Manager.
  469.     Inputs:
  470.                 stream_t            The stream to flush.
  471.     Outputs:
  472.     Notes:
  473.                 Stream data may still reside in the File Manager's caches, but any changes will have
  474.                 been written out by the File Manager.  Note that the underlying device's driver, or
  475.                 the device itself, may cache some data, so the File Manager cannot guarantee that
  476.                 all data has actually been written to the underlying media.
  477.                 
  478.                 Other information about the object (such as its modification date) might not be flushed
  479.                 by this call, though any volume-level data needed to access the stream will be.
  480.  
  481.  
  482. */
  483. extern OSStatus FSStreamFlush(FSStreamObjID stream_t);
  484.  
  485. /*
  486.     Function:    FSStreamGetAbsoluteEOF
  487.     Purpose:    Get the logical end-of-file of an open file fork.
  488.     Inputs:
  489.                 stream_t            The target stream.
  490.     Outputs:
  491.                 currentEOF_o        The logical end-of-file of the specified
  492.                                     stream.
  493.     Notes:
  494. */
  495. extern OSStatus FSStreamGetAbsoluteEOF(FSStreamObjID stream_t, FSOffset *currentEOF_o);
  496.  
  497. /*
  498.     Function:    FSStreamGetMark
  499.     Purpose:    Returns the current mark (position offset) for a stream.
  500.     Inputs:
  501.                 stream_t            The stream.
  502.     Outputs:
  503.                 currentMark_o        Current offset in the stream, stream_t.
  504.     Notes:
  505.                 This call returns the offset from the start of the file that would be
  506.                 equivalent to using a FSForkPositionDescriptor whose positionOffset is
  507.                 0, and whose positionMode is kFSFromMark.  A stream's mark is set to
  508.                 the byte following the last read or write, or via FSStreamSetMark.
  509. */
  510. extern OSStatus FSStreamGetMark(FSStreamObjID stream_t, FSOffset *currentMark_o);
  511.  
  512. /*
  513.     Function:    FSStreamOpen
  514.     Purpose:    Open a file fork for stream access.
  515.     Inputs:
  516.                 fileObjectRef_t        The object ref of the file to open.
  517.                 fork_i                The fork to open.
  518.     Outputs:
  519.                 stream_o            The new stream ID.
  520.     Notes:
  521.                 The only allowable values for fork_i are kFSDataFork and
  522.                 kFSResourceFork.
  523.                 
  524.                 FSStreamOpen attempts to open the fork with exclusive read/write
  525.                 access. If the file is locked or is open on another stream with
  526.                 conflicting access constraints, then an error is returned. Use
  527.                 FSStreamOpenWithConstraints() to specify particular access
  528.                 constratins.
  529. */
  530. extern OSStatus FSStreamOpen(FSObjectRef fileObjectRef_i, FSForkType fork_i, FSStreamObjID *stream_o);
  531.  
  532. /*
  533.     Function:    FSStreamSetAbsoluteEOF
  534.     Purpose:    Set the logical end-of-file of an open file fork.
  535.     Inputs:
  536.                 stream_t            The target stream.
  537.                 eof_i                The new logical end-of-file of the stream.
  538.     Outputs:
  539.     Notes:
  540.                 If there is not enough space on the volume to set the EOF of
  541.                 the fork specified by stream_t to eof_i, then the EOF is not
  542.                 changed and an error is returned.
  543. */
  544. extern OSStatus FSStreamSetAbsoluteEOF(FSStreamObjID stream_t, const FSOffset *eof_i);
  545.  
  546. /*
  547.     Function:    FSStreamSetMark
  548.     Purpose:    Sets the current mark (position offset) for a stream.
  549.     Inputs:
  550.                 stream_t            The stream.
  551.                 newPosition_i        The new position of the stream's mark.
  552.                 options_i
  553.     Outputs:
  554.                 originalMark_o        The stream's mark, before being changed (relative
  555.                                     to the start of the stream).
  556.                 currentMark_o        The new mark, relative to the start of the stream.
  557.     Notes:
  558.                 A stream's mark is usually used for sequential access to a stream,
  559.                 or to position relative to the ending position of the last operation
  560.                 on a stream.  This call lets you explicitly set the mark for future
  561.                 operations that will operate relative to the current mark.
  562.                 
  563.                 If kFSMarkPinToEOF is set in options_i, and the new position specified
  564.                 by newPosition_i would exceed the current end of the stream (also known
  565.                 as End Of File or EOF), then the mark will be set to the EOF and E_NoError
  566.                 is returned.  Otherwise, an error will returned.  The mark may never be
  567.                 set past the end of the stream.
  568.  
  569.  
  570. */
  571. extern OSStatus FSStreamSetMark(FSStreamObjID stream_t, const FSForkPositionDescriptor *newPosition_i, FSStreamSetMarkOptions options_i, FSOffset *originalMark_o, FSOffset *currentMark_o);
  572.  
  573. /*
  574.     Function:    FSStreamSimpleRead
  575.     Purpose:    Read data from an open stream.
  576.     Inputs:
  577.                 stream_t            The target stream.
  578.                 requestLength_i        The number of bytes to read from the fork.
  579.                 position_i            The starting position for the read operation
  580.                 
  581.     Outputs:
  582.                 data_o                The address of a buffer to the read bytes.
  583.                 actualLength_o        The actual number of bytes read from the file (optional).
  584.                 currentMark_o        The mark position within the stream after the
  585.                                     read operation (optional)
  586.     Notes:            
  587.                 The stream mark is always positioned after the last byte read after all
  588.                 calls to FSStreamSimpleRead().
  589.  
  590.                 If an attempt is made to read beyond the logical EOF of the fork, then
  591.                 the mark is set at the logical EOF of the file, actualLength_o contains
  592.                 the actual number of bytes read, and an error is returned.
  593. */
  594. extern OSStatus FSStreamSimpleRead(FSStreamObjID stream_t, ByteCount requestLength_i, const FSForkPositionDescriptor *position_i, LogicalAddress data_o, ByteCount *actualLength_o, FSOffset *currentMark_o);
  595.  
  596. /*
  597.     Function:    FSStreamSimpleWrite
  598.     Purpose:    Write data to an open stream.
  599.     Inputs:
  600.                 stream_t            The target stream.
  601.                 requestLength_i        The number of bytes to write to the fork.
  602.                 data_i                The address of a buffer contating the data to write.
  603.                 position_i            The starting position for the write operation
  604.                 
  605.     Outputs:
  606.                 actualLength_o        The actual number of bytes written to the file (optional).
  607.                 currentMark_o        The mark position within the stream after the
  608.                                     read operation (optional)
  609.     Notes:            
  610.                 The stream mark is always positioned after the last byte written after all
  611.                 calls to FSStreamSimpleWrite().
  612.  
  613.                 If an attempt is made to write beyond the logical EOF of the fork, then
  614.                 the EOF is moved to the byte following the last written byte.
  615. */
  616. extern OSStatus FSStreamSimpleWrite(FSStreamObjID stream_t, ByteCount requestLength_i, ConstLogicalAddress data_i, const FSForkPositionDescriptor *position_i, ByteCount *actualLength_o, FSOffset *currentMark_o);
  617.  
  618. /*
  619. ============================================================================
  620.     Memory-mapped Access Method(Backing Store Requests)
  621. ============================================================================
  622. */
  623. /*
  624.     Function:    FSMappedFileClose
  625.     Purpose:    Closes an access path to a file used for backing store.
  626.     Inputs:
  627.                 backingStore_t        The backing store object.
  628.     Outputs:
  629.     Notes:
  630.                 Basically the same as FSStreamClose, but for a backing store.
  631.                 
  632.                 All data written to this backing store (by writing to pages backed by
  633.                 this store) will be flushed (written) by the File Manager.
  634. */
  635. extern OSStatus FSMappedFileClose(FSBackingStoreObjID backingStore_t);
  636.  
  637. /*
  638.     Function:    FSMappedFileFlush
  639.     Purpose:    Any data written via the backing store will be written by the File Manager.
  640.     Inputs:
  641.                 backingStore_t        The backing store to flush.
  642.     Outputs:
  643.     Notes:
  644.                 Data may still reside in the File Manager's caches, but any changes will have been
  645.                 written out by the File Manager.  Note that the underlying device's driver, or the
  646.                 device itself, may cache some data, so the File Manager cannot guarantee that all
  647.                 data has actually been written to the underlying media.
  648.                 
  649.                 Other information about the object (such as its modification date) might not be flushed
  650.                 by this call, though any volume-level data needed to access the fork data will be.
  651. */
  652. extern OSStatus FSMappedFileFlush(FSBackingStoreObjID backingStore_t);
  653.  
  654. /*
  655.     Function:    FSMappedFileGetAbsoluteEOF
  656.     Purpose:    Return the EOF (length) of the fork being accessed by the given backing store.
  657.     Inputs:
  658.                 backingStore_t        The backing store used to access the fork.
  659.     Outputs:
  660.                 currentEOF_o        The size, in bytes, of the fork.
  661.     Notes:
  662.                 Since access to a fork via a backing store (i.e. memory mapped file access) is
  663.                 accomplished by directly accessing memory pages, the virtual memory system must
  664.                 read and write entire pages.  If the last page is modified, the entire page is
  665.                 written, resulting in the fork size being rounded up to a multiple of a page size.
  666.                 Similarly for access to pages beyond the fork's EOF.
  667.                 
  668.                 This call returns the current EOF (length) of the underlying fork.  This may be
  669.                 set implicitly by writing to backed pages, or by using the FSMappedFileSetEOF
  670.                 call.  It may also be changed by streams opened to the same fork.
  671. */
  672. extern OSStatus FSMappedFileGetAbsoluteEOF(FSBackingStoreObjID backingStore_t, FSOffset *currentEOF_0);
  673.  
  674. /*
  675.     Function:    FSMappedFileOpen
  676.     Purpose:    Open a file fork for memory mapped access.
  677.     Inputs:
  678.                 fileObjectRef_t        The object ref of the file to open.
  679.                 fork_i                The fork to open.
  680.     Outputs:
  681.                 backingStore_o        The backing store used to access the fork.
  682.     Notes:
  683.                 The only allowable values for fork_i are kFSDataFork and
  684.                 kFSResourceFork.
  685.                 
  686.                 FSMappedFileOpen attempts to open the fork with exclusive read/write
  687.                 access. If the file is locked or is open on another stream with
  688.                 conflicting access constraints, then an error is returned. Use
  689.                 FSMappedFileOpenWithConstraints() to specify particular access
  690.                 constratins.
  691. */
  692. extern OSStatus FSMappedFileOpen(FSObjectRef fileObjectRef_t, FSForkType fork_i, FSBackingStoreObjID *backingStore_o);
  693.  
  694. /*
  695.     Function:    FSMappedFileSetAbsoluteEOF
  696.     Purpose:    Sets the EOF (length) of the fork being accessed by the given backing store.
  697.     Inputs:
  698.                 backingStore_t        The backing store used to access the fork.
  699.                 eof_i                The new length (EOF) of the fork.
  700.     Outputs:
  701.                 currentEOF_o        The new size, in bytes, of the fork.
  702.     Notes:
  703.                 Since access to a fork via a backing store (i.e. memory mapped file access) is
  704.                 accomplished by directly accessing memory pages, the virtual memory system must
  705.                 read and write entire pages.  If the last page is modified, the entire page is
  706.                 written, resulting in the fork size being rounded up to a multiple of a page size.
  707.                 Similarly for access to pages beyond the fork's EOF.
  708.                 
  709.                 This call allows the EOF to be explicitly set for a fork being accessed via a
  710.                 backing store.  Any data beyond the EOF will not actually be written to the fork.
  711.                 The File Manager has no way to detect whether access to pages occurs beyond the
  712.                 EOF; it is a programming error to access bytes beyond the EOF via a backing store.
  713.                 
  714.                 This call would typically be used when a fork has been memory mapped to enable
  715.                 convenient access to a file's data structures as if it were completely in memory.
  716.                 You would make all changes to the data structures, then use this call to indicate
  717.                 the number of bytes that are valid and should be written to the fork.
  718. */
  719. extern OSStatus FSMappedFileSetAbsoluteEOF(FSBackingStoreObjID backingStore_t, const FSOffset *eof_i, FSOffset *currentEOF_o);
  720.  
  721. /*
  722. ****************************************************************************
  723.     NAVIGATION & ENUMERATION
  724. ****************************************************************************
  725. */
  726. /*
  727. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  728.     Object Iteration
  729. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  730. */
  731. /*
  732.     Function:    FSObjectIterateOnce
  733.     Purpose:    Iterate to the next object in the current container and get
  734.                 aggregate property information.
  735.     Inputs:
  736.                 iterator_t                The object iterator.
  737.                 objectInfoVersion_i        The version of the FSObjectInformation data record
  738.                                         specified by objectInfo_o.
  739.     Outputs:
  740.                 objectInfo_o            Aggregate property information about the current
  741.                                         iterator object (optional).
  742.                 objectRef_o                The object ref of the current iterator object (optional).
  743.                 objectName_o            The name of the current iterator object (optional).
  744.     Notes:
  745.                 Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
  746.                 version of the FSObjectInformation record. infoVersion_i is ignored
  747.                 if objectInfo_o is omitted.
  748.                 
  749.                 objectName_o, if specified, must reference a preinitialized persistent
  750.                 TextObject of sufficient size to contain the object's name.
  751.  
  752.                 If the iterator has reached the end of it's current container, then an
  753.                 exception will be returned.
  754. */
  755. extern OSStatus FSObjectIterateOnce(FSObjectIteratorObjID iterator_t, FSInfoVersion objectInfoVersion_i, FSObjectInformation *objectInfo_o, FSObjectRef *objectRef_o, FSName objectName_o);
  756.  
  757. /*
  758.     Function:    FSObjectIteratorChangeCurrentScope
  759.     Purpose:    Move an object iterator into or out of a container.
  760.     Inputs:
  761.                 iterator_t        The object iterator.
  762.                 movement_i        The direction to move: into or out of a container.
  763.     Outputs:
  764.     Notes:
  765.                 If movement_i is kFSObjectEnter, then the iterator must be positioned on
  766.                 an object that is capable of containing other objects; it does not need to
  767.                 actually contain any objects at that time.  That object will become the new
  768.                 current scope of the iterator and it will be in Start Of Iteration state
  769.                 (meaning that all objects in the current scope have yet to be returned).
  770.                 The iterator will not be positioned on any object.
  771.                 
  772.                 If movement_i is kFSObjectExit,  then the current scope will become the object
  773.                 that contains the current scope; the iterator's new position will be the object
  774.                 that was the current scope.  If the current scope and the outermost scope were
  775.                 the same, then the outermost scope will also change to the new current scope and
  776.                 E_ExitIteratorScope is returned (so that you realize you will be iterating outside
  777.                 of the scope that you used to create the iterator; the iterator remains usable).
  778.                 
  779.                 Object iterators keep track of all of the objects between the outermost scope and
  780.                 the current scope (this is known as the "scope stack").  If any object in the scope
  781.                 stack is moved, the iterator is invalidated and will return the error
  782.                 E_IteratorScopeException until it has been explicitly fixed (by FSObjectIteratorRecreate)
  783.                 or disposed.  This call adds or removes objects from the scope stack.
  784. */
  785. extern OSStatus FSObjectIteratorChangeCurrentScope(FSObjectIteratorObjID iterator_t, FSObjectIteratorMovement movement_i);
  786.  
  787. /*
  788.     Function:    FSObjectIteratorCreate
  789.     Purpose:    Create an iterator for iterating over objects.
  790.     Inputs:
  791.                 outermostScope_t        The initial outermost scope and current scope.
  792.                 options_i                Controls whether the iterator will traverse objects in
  793.                                         a single container or all embedded (nested) containers.
  794.                                         Also controls which kinds of objects will be returned.
  795.     Outputs:
  796.                 iterator_o                The object iterator.
  797.     Notes:
  798.                 The outermost scope and current scope of the iterator are set to outermostScope_t.
  799.                 The iterator is not positioned on any object, though it is inside outermostScope_t.
  800.                 OutermostScope_t must be an object capable of containing other objects (such as the
  801.                 Universe, a volume set, a volume, or a folder).  The iterator is put into "Start Of
  802.                 Iteration" state, meaning that all objects in the current scope have yet to be
  803.                 returned.
  804.                 
  805.                 The File Manager allocates resources and maintains state for every iterator.  When
  806.                 you have finished using an iterator, you should call FSObjectIteratorDispose to dispose
  807.                 of it.
  808. */
  809. extern OSStatus FSObjectIteratorCreate(FSObjectRef outermostScope_t, FSObjectIteratorCreationOptions options_i, FSObjectIteratorObjID *iterator_o);
  810.  
  811. /*
  812.     Function:    FSObjectIteratorDispose
  813.     Purpose:    Dispose of an object iterator.
  814.     Inputs:
  815.                 iterator_t        The object iterator.
  816.     Outputs:
  817.     Notes:
  818.                 The File Manager will dispose of the iterator and release any resources
  819.                 allocated to the iterator.  Further attempts to use the iterator will result
  820.                 in an error.
  821.  
  822.  
  823. */
  824. extern OSStatus FSObjectIteratorDispose(FSObjectIteratorObjID iterator_t);
  825.  
  826. /*
  827.     Function:    FSObjectIteratorRestart
  828.     Purpose:    Place an object iterator in the Start Of Iterator state, in its current scope.
  829.     Inputs:
  830.                 iterator_t        The object iterator.
  831.     Outputs:
  832.     Notes:
  833.                 The iterator is not positioned on any object.  The iterator is put into "Start Of
  834.                 Iteration" state, meaning that all objects in the current scope have yet to be
  835.                 returned.
  836.                 
  837.                 You would use this call to completely restart iteration within the current scope,
  838.                 ignoring any state about objects previously returned in the current scope.  The
  839.                 outermost scope is not affected.  State information about which objects have been
  840.                 returned from scopes outside the current scope is unchanged.
  841. */
  842. extern OSStatus FSObjectIteratorRestart(FSObjectIteratorObjID iterator_t);
  843.  
  844. /*
  845. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  846.     Object Resolution
  847. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  848. */
  849. /*
  850.     Function:    FSObjectCreateRef
  851.     Purpose:    Get the object ref for a named object in a given container.
  852.     Inputs:
  853.                 container_i                The object container ref.
  854.                 objectName_i            The name of the target object.
  855.     Outputs:
  856.                 objectRef_o                The resulting object ref.
  857.     Notes:
  858. */
  859. extern OSStatus FSObjectCreateRef(FSObjectRef container_i, ConstFSName objectName_i, FSObjectRef *objectRef_o);
  860.  
  861. /*
  862.     Function:    FSObjectExchange
  863.     Purpose:    Exchange the properties of two objects.  Typically used for "safe
  864.                 saving", while maintaining an object's persistent reference.
  865.     Inputs:
  866.                 object1_i        One object.
  867.                 object2_i        The object to exchange it with.
  868.     Outputs:
  869.     Notes:
  870.                 This call is used to allow a "safe save" that preserves an object's
  871.                 persistent reference.  For example, you might want to save an updated
  872.                 set of properties to an object so that any errors while saving result
  873.                 in the object being unchanged; but, you also want the object's persistent
  874.                 reference to remain unchanged (so that things like aliases still work).
  875.                 
  876.                 What you would do is create a second object somewhere (in a temporary
  877.                 folder, for example).  Write out all of the properties, both unchanged
  878.                 and changed, to the second object.  When done saving, you would call
  879.                 FSObjectExchange with both objects; the contents of the two objects get
  880.                 swapped in such a way that the original object has the new properties,
  881.                 but retains its old persistent reference.
  882.  
  883.  
  884. */
  885. extern OSStatus FSObjectExchange(FSObjectRef object1_i, FSObjectRef object2_i);
  886.  
  887. /*
  888.     Function:    FSObjectGetContainerRef
  889.     Purpose:    Get the object ref for the container of a given object.
  890.     Inputs:
  891.                 objectRef_i                The object of interest.
  892.     Outputs:
  893.                 containerRef_o            The object ref of the container of
  894.                                         containerRef_o.
  895.     Notes:
  896. */
  897. extern OSStatus FSObjectGetContainerRef(FSObjectRef objectRef_i, FSObjectRef *containerRef_o);
  898.  
  899. /*
  900.     Function:    FSObjectRefGetFSSpec
  901.     Purpose:    Return an FSSpec for an object (suitable for use with the Files API).
  902.     Inputs:
  903.                 object_t            The object.
  904.     Outputs:
  905.                 fSSpec_o            An FSSpec that specifies the same object as object_t,
  906.                                     suitable for use with the Files API.
  907.     Notes:
  908.                 This call is intended to be used by code that is required to use both the
  909.                 Files API and the FileManager API (or has clients that use both APIs).
  910.                 For example, a piece of code may already exist with an API that uses FSSpecs,
  911.                 but has been converted internally to use the FSObjectRefs; it would use this
  912.                 call to produce an FSSpec as an output for the pre-existing API.
  913.                 
  914.                 It would be best to provide an API that allows its clients to use FSObjectRefs.
  915. */
  916. extern OSStatus FSObjectRefGetFSSpec(FSObjectRef object_t, FSSpec *fSSpec_o);
  917.  
  918. /**/
  919. extern OSStatus FSPathnameResolve(FSObjectRef container_i, const char *path_i, ByteCount pathLength_i, FSPathnameType pathType_i, FSObjectRef *objectRef_o);
  920.  
  921. /*
  922.     Function:    FSSpecGetFSObjectRef
  923.     Purpose:    Return an FSObjectRef for an object specified via an FSSpec.
  924.     Inputs:
  925.                 theFSSpec_t            An FSSpec for the object.
  926.     Outputs:
  927.                 theObject_o            An FSObjectRef for the object.
  928.     Notes:
  929.                 This call is intended to be used by code that is required to use both the
  930.                 Files API and the FileManager API (or has clients that use both APIs).
  931.                 For example, a piece of code may already exist with an API that uses FSSpecs,
  932.                 but has been converted internally to use the FSObjectRefs; it would use this
  933.                 call to take an input FSSpec and convert it to an FSObjectRef to use internally;
  934.                 the FSObjectRef would then be disposed before completing the call.
  935.                 
  936.                 It would be best to provide an API that allows its clients to use FSObjectRefs.
  937. */
  938. extern OSStatus FSSpecGetFSObjectRef(const FSSpec *theFSSpec_t, FSObjectRef *theObject_o);
  939.  
  940. /*
  941.     Function:    FSVolumeGetInformation
  942.     Purpose:    Get the volume object ref for a given volume object ID.
  943.     Inputs:
  944.                 volume_t        The volume's object ID.
  945.     Outputs:
  946.                 object_o        The volume's object ref.
  947.     Notes:
  948. */
  949. extern OSStatus FSVolumeGetInformation(FSVolumeObjID volume_t, FSObjectRef *object_o);
  950.  
  951. #define FSObjectGetOnePropertyValue        FSObjectGetOneProperty
  952. #define FSObjectSetOnePropertyValue        FSObjectSetOneProperty
  953. #define FSVolumeObjIDResolve            FSVolumeGetInformation
  954. #define FSBackingStoreClose                    FSMappedFileClose
  955. #define FSBackingStoreFlush                    FSMappedFileFlush
  956. #define FSBackingStoreGetAbsoluteEOF        FSMappedFileGetAbsoluteEOF
  957. #define FSBackingStoreOpen                    FSMappedFileOpen
  958. #define FSBackingStoreSetAbsoluteEOF        FSMappedFileSetAbsoluteEOF
  959. extern OSStatus FSObjectGetOnePropertySize(FSObjectRef objectRef_t, const FSProperty *property_i, FSSize *propertySize_o);
  960.  
  961. #endif
  962. #endif
  963.  
  964. #pragma options align=reset
  965. #endif /* PRAGMA_ALIGN_SUPPORTED */
  966.  
  967. #if PRAGMA_IMPORT_SUPPORTED
  968. #pragma import off
  969. #endif
  970.  
  971. #ifdef __cplusplus
  972. }
  973. #endif
  974.  
  975. #endif /* __FILEMANAGER__ */
  976.  
  977.